# Interactive Activities — Execution Plan

Systematize the Matching process across all 8 formats: one shared style foundation, per-activity prototypes, grade-level theming, and a repeatable handoff.

> **Status (current):** Phase 0 (foundation) and the build phase are **done** — all 8 activities are built on the shared foundation. Two things evolved from the original plan below and are corrected throughout: (1) there is **no `core.js`** — each activity is a self-contained file with its own JS (the trade we accepted to keep the finalized Matching design intact); `global.css` is the single shared file (tokens + component styles). (2) Grade theming recolors **only the top bar** (each grade's Main color); the dotted background and everything else stay shared. Also note: three formats (Dice Roller, Multiple Choice, Flashcards) were already redesigned on the platform and were re-skinned to the Matching standard.

**Framing: the handoff ≈ production.** Engineering is not componentizing anything — the agreed deliverable is vanilla HTML/CSS/JS files. So this project structure *is* the shipping structure, and these files are close to what goes live. Build to production fidelity, not prototype fidelity: keep the real data fetch, real states, and real behavior; only the few things that need engineering's systems stay as placeholders (see below).

## Project structure (as built)

```
Interactive Activities 2026/            ← project folder
  global.css                            ← the ONE shared file: tokens + component styles
  activities/
    matching/index.html                 ← each links ../../global.css and holds only
    sorting/index.html                     its activity-specific CSS + its own JS
    q-and-a/index.html
    spinner/index.html
    dice-roller/index.html
    fill-in-the-blanks/index.html
    multiple-choice/index.html
    flashcards/index.html
  assets/
    shared/                             ← logos, icons, celebration art
    matching/                           ← per-activity illustrator assets (added as art arrives)
  docs/                                 ← Execution Plan, Phase 1 Recon, colors-and-buttons, Matching brief
  README.md
```

Each `activities/*/index.html` links `../../global.css` and contains **only what's unique**: its cards, its mechanic, and its own JS.

## The shared foundation

**`global.css` — the single shared file.** Holds the design **tokens** (colors, spacing, type, radius, shadows, buttons, grade palettes — edit here to rebrand) *and* the shared **component styles** (buttons, start/end modals, top bar, toolbar, toast, states) plus the three grade themes. Cards are NOT here — they're unique per activity.

**Shared logic lives inline in each activity (no `core.js`).** The data fetch, start/end + completion modals, correction modes (reveal-at-end vs. as-you-go), TTS, parent `postMessage`, loading/error states, the Review Goals/Concepts button, and the grade switch are implemented in each activity's own `<script>`. This is the trade we made to keep the finalized Matching design fully intact — the shared *look* is centralized in `global.css`, but the shared *logic* is duplicated per file.

*Implication for rebrand: visual changes are one-place edits in `global.css`. A change to shared behavior (e.g., the completion flow) would mean editing each activity file. If that becomes painful later, the logic can be lifted into a shared script then.*

## Grade-level theming (kept deliberately simple)

- `global.css` defines three body classes — `body.grade-lower`, `body.grade-upper`, `body.grade-mh` — each of which recolors **only the top bar** to that grade's Main color (`#F2EDB1` / `#BDDBFF` / `#F5F2ED`). The dotted background, cards, and everything else are identical across all three.
- The **"Grade level" dropdown lives in the prototype toolbar — the same rack as the "paste any id" box — not inside any activity.** It's purely a review control that toggles the grade class on `<body>`; nothing in the activity itself changes.
- The whole prototype toolbar (id box + grade switch) comes out at handoff. The engineers decide how the real grade signal is sourced (likely passed in at launch like `userId`, since grade is contextual, not content). The dropdown exists only so reviewers can see all three versions.

## Phases

**Phase 0 — Foundation first (build and lock the shared file). ✓ DONE.** Created the project folder + structure. Built `global.css` (tokens + shared components) by extracting the shared styling out of the Matching prototype; refactored Matching into `activities/matching/index.html` that consumes it. The foundation was finalized and validated against Matching before any of the other 7 began.

**Phase 1 — Recon (7 formats). ✓ DONE.** Fetched each payload shape (public endpoint, no login), extracted the mechanic / config flags / states, and screenshotted each live render. Output: `docs/Phase 1 Recon - 7 Formats.md`. (Surfaced that Dice Roller, Multiple Choice, and Flashcards were already redesigned on the platform.)

**Phase 2 — Build the 7 first-draft prototypes. ✓ DONE.** Each activity file links `global.css` and adds only its unique cards + mechanic + JS, all states, TTS, and correction modes where applicable. The already-redesigned three were re-skinned to the Matching standard. (The grade-level switch is a review-only control in the prototype toolbar, not part of any activity.)

**Phase 3 — Refine with you.** ← current. You review/iterate each design; I adjust. This is the part that stays human — it's where your taste lives.

**Phase 4 — Per-format handoff.** Since the files ship close to as-is, the handoff is mostly the files themselves plus a short note of the few things that still need engineering's systems. Share via **staging links** (not the Slack HTML preview — it sandboxes the fetch).

**What still needs engineering (the only real placeholders):**
- **The exact parent `postMessage` schema** (progress/finish) — I replicate the events; they confirm the payload shape.
- **TTS** — the control and behavior are real, but ElevenLabs needs a server proxy + key, so the prototype demos with the browser voice until that's wired.
- **The grade-level source** — the dropdown is the review switch; they decide where the real grade signal comes from.
- **Drag engine decision** — the prototype uses dependency-free native drag, which fits the vanilla/no-dependency goal better than GSAP. Worth confirming with them, and note native drag needs pointer-event handling for solid touch support.

## Can Claude build all 7 "at the same time"?

Not literally in parallel — Chrome DevTools drives one browser/session, so simultaneous automation collides, and fully auto-generated design wouldn't match your eye. But the *repetitive* part parallelizes well: because the app is one shared bundle and the content endpoint is public, I can recon all 7 back-to-back quickly and generate the 7 scaffolds as a batch. So ~80% (recon + scaffolding + wiring to `global.css`) is automated; the ~20% that needs your judgment (design refinement) stays with you, sequentially.

## Inputs (all received)

1. **7 representative live activity ids** — provided.
2. **The 3 grade palettes** — provided and finalized as tokens in `global.css`.
3. **Shared logic decision** — resolved: no `core.js`; each activity is self-contained (to preserve the finalized Matching design). `global.css` is the single shared file.
4. **Project folder** — `Desktop/Interactive Activities 2026`.

## Risks / notes

- **Mechanics differ per format** — Spinner and Dice Roller involve randomness; Q&A, Multiple Choice, and Fill in the Blanks aren't drag-matching. `global.css` supplies the shared look; each activity's shell + mechanic lives in its own file.
- **Payload config flags confirmed** per format (see the recon doc): `isAutoCheck` on Matching/Sorting/Fill-in-Blanks; `isCorrect` on Multiple Choice; the rest are open/random/study (no scoring).
- **Frozen contract per format** — same endpoint, field names, match/answer logic, and parent `postMessage`.
- **Device support** to check when refining: the CSS-mask puzzle cards (Matching), the vanilla animations (wheel/dice/flip), and drag on older Chromebooks/iPads/Safari.
- **Sharing** — use staging links; the Slack inline preview blocks the network call.
- **Open confirmations** — completion triggers for the non-scored formats (Q&A/Spinner/Dice = Done; Flashcards = last card), and the "already-redesigned 3" being re-skinned to the Matching standard.
